home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DS-CD ROM 2 1993 August
/
DS CD-ROM 2.Ausgabe (August 1993).iso
/
programm
/
ds0257
/
doc.exe
/
ENV.DOC
< prev
next >
Wrap
Text File
|
1992-02-13
|
14KB
|
357 lines
─────────────────────────────────────────────────────────────────────────────
Dokumentation zur Datei: ENV.INC
─────────────────────────────────────────────────────────────────────────────
ENV.INC - Routinen zur Bearbeitung des Environments
(für den Assembler A86)
(c) Bernd Schemmer 1990 - 1992
Letzter Update: 13.02.1992
■ Hinweis:
----------
Alle Strings besitzen einen Längenzähler (erstes Byte) Deshalb kann
ein Eintrag im Environment (Name, Inhalt und Gleicheitszeichen) max.
255 Zeichen lang sein.
Alle Routinen arbeiten auf dem aktuellen Environment. Das aktuelle
Environment kann das lokale Environment (= Environment dieses
Programms), das Environment des aufrufenden Programmes oder das
Master-Environment des Kommando-Interpreters (normalerweise der
COMMAND.COM, bei 4DOS eingeschränkt, siehe Dokumentation zu 4DOS)
sein. Zum Umschalten des aktuellen Environments dient die Routine
'UseOtherEnv'. Voreingestellt für das aktuelle Environment ist das
lokale Environment.
Falls eines der Environmente über andere Routinen als die in dieser
Datei zusammengestellten verändert wird, muß die Routine 'InitEnv-
Routines' vor der weiteren Benutzung der Routinen aufgerufen werden!
Zur Initialisierung sollte zu Programmbeginn einmal die Routine
'InitEnvRoutines' aufgerufen werden.
Die Routinen zur Bearbeitung des Environments des aufrufenden
Programms benutzen das undokumentierte Feld mit dem Offset 16h im
PSP (= PSP-Segment des aufrufenden Programmes), die Routinen zur
Bearbeitung des Master-Envrionments benutzen die undokumentierte
Funktion 52h des Interrupt 21h, den undokumentierten DOS-Info-Block
und die undokumentierten MCBs.
Die Routinen können nur bei DOS-Version ab 3.0 eingesetzt werden
(muß von der aufrufenden Routine überprüft werden!).
Die Routinen gehen davon aus, daß die Master-Kopie des COMMAND.COM
den zweiten Speicherblock belegt. Falls dem nicht so ist, sollte
ein Programm zuerst die Routine 'InitEnvRoutines' aufrufen und dann
die Variable 'CommandEnvSeg' direkt auf den korrekten Wert setzen.
Falls die Routinen mit einen Fehler enden, bedeutet dies normaler-
weise (d.h. es ist nichts anderes angegeben), daß das aktuelle
Environment nicht nutzbar ist.
■ Variablen:
------------
LokalEnvSeg - Segment des lokalen Environments
Sonderfall: 0 - Segment noch nicht ermittelt
-1 - Segment wurde freigegeben
CallerEnvSeg - Segment des Environments des aufrufenden
Prozesses
Sonderfall: 0 - Segment noch nicht ermittelt
-1 - Segment nicht ermittelbar
CommandEnvSeg - Segment des Master-Environments des COMMAND.COM
Sonderfall: 0 - Segment noch nicht ermittelt
-1 - Segment nicht ermittelbar
■ Routinen:
-----------
GetProgName - Ermittelt den Namen des Programms aus
dem Environment
EnvCount - Ermittelt die Anzahl der Einträge im
Environment
GetEnvData - Ermittelt die Speicherdaten des aktuellen
Environments
EnvStr - Ermittelt einen best. Environment-Eintrag
EnvParse - Splittet einen Environment-Eintrag in Name
und Inhalt
SearchEnvStr - Ermittelt den Inhalt einer vorgegebenen
Environment-Variable
FreeLokalEnv - Gibt das lokale Environment frei
UseOtherEnv - Wechselt das aktuelle Environment
UsedEnvSeg? - Ermittelt des aktuelle Environment
GetCallerName - Ermittelt den Namen des aufrufenden Programmes
SetEnvVar - Erstellt, löscht oder ändert eine Environment-
Variable
InitEnvRoutine - Initialisiert die Routinen und Daten
und falls nötig:
Upcase - Konvertiert ein Zeichen in Großbuchstaben
ParseStr - Splittet einen String ab einen vorgegebenen
Zeichen
DOSStrToStr - Konvertiert einen DOS-String ins Stringformat
■ Konstanten:
-------------
UseLokalEnv EQU 0 ; Byte, EQU-Anweisungen für das akt.
UseCallerEnv EQU 1 ; Environment
UseCOMMANDEnv EQU 2
----------------------------
SetEnvVar
Funktion: Setzen, Ändern oder Löschen einer Variable im aktuellen
Environment
Eingabe: DS:SI -> Name der Variable als String
Das Zeichen '=' und Nullbytes dürfen im Namen
nicht vorkommen.
ES:DI -> neuer Inhalt der Variablen als String
Im String darf kein Nullbyte vorkommen.
(leerer String ->> löschen der Variable)
Ausgabe: Der Name wird in Großbuchstaben konvertiert.
CF = 0 ->> okay
und bei Löschen:
ZF = 1 ->> Variable ist nicht vorhanden
ZF = 0 ->> Variable gelöscht
CF = 1 ->> Fehler, Grund:
bei Setzen/Ändern/Löschen:
akt. Environment nicht mehr gültig
oder
'=' oder Nullbyte im Namen enthalten
oder
Nullbyte im Inhalt enthalten
oder
Leerer String als Namen angegeben
oder bei Setzen/Ändern:
Environmentüberlauf
Bes.: Mit dieser Routine können Environment-Einträge mit max.
501 Zeichen Länge erstellt werden (max. 255 Zeichen für
den Namen, max. 255 Zeichen für den Inhalt und 1 Zeichen
für den Trenner '=').
Einträge länger als 255 Zeichen (Name, Inhalt und Gleich-
heitszeichen) können aber von den restlichen Routinen
NICHT bearbeitet werden!
Bei einem Überlauf des Environments wird eine existierende
Variable auf jeden Fall gelöscht. Soll dies verhindert
werden, muß vorher über die Routine 'GetEnvData' die Anzahl
der freien Bytes im aktuellen Environment und über 'GetEnvVar'
die Länge der evtl. schon bestehenden Variable überprüft
werden. Die Länge des neuen Eintrags kann folgendermaßen
berechnet werden:
Länge des Namens
+ Länge des Inhaltes
+ 1 (für das Zeichen '=')
und, falls schon Variablen im Environment vorhanden
sind:
+ 1 (für das Endekennzeichen des Eintrages)
----------------------------
SearchEnvStr
Funktion: Ermittelt den Inhalt einer durch den Namen angegebenen
Environment-Variable aus dem aktuellen Environment.
Eingabe: DS:SI -> Name der Variablen als String
ES:DI -> Puffer für den Inhalt
Ausgabe: CF = 0 ->> Gefunden
ES:DI -> Inhalt als String
CF = 1 ->> nicht gefunden
ES:DI -> leerer String
ACHTUNG: Die Routine benötigt ca. 540 Byte auf dem Stack
(u.a. für lokale Variable)
Für den String und den Puffer kann die gleiche Variable
verwendet werden (der Name wird dann aber in jeden Fall
überschrieben oder gelöscht)
----------------------------
EnvParse
Funktion: Splittet einen Eintrag aus dem Environment in den Namen
und den Inhalt (das '=' wird verworfen)
Eingabe: DS:SI -> Namen und Inhalt der Variable als String
ES:DI -> Puffer für den Inhalt
Ausgabe: CF = 0 ->> Parsen ok
DS:SI -> Name als String
ES:DI -> Inhalt als String
CF = 1 ->> Parsen fehlerhaft (->> kein Gleichheitszeichen
gefunden) Der Name ist unverändert und der Puffer
ist gelöscht.
Bes.: Falls der Quellstring mehr als ein Gleichheitszeichen enthält,
wird nur das erste berücksichtigt.
Die beiden Strings müssen verschieden sein.
----------------------------
EnvStr
Funktion: Ermittelt den Eintrag mit der Nummer aus AL aus dem
Environment
Eingabe: AL = Nummer des Eintrages (Zählung beginnt bei 1)
ES:DI -> Puffer für den Eintrag
Ausgabe: CF = 0 ->> okay
ES:DI -> String im Puffer falls Eintrag
vorhanden oder leerer String im
Puffer falls Eintrag nicht vorhanden
CF = 1 ->> Fehler
ES:DI -> leerer String
Bes.: Falls als Nummer 0 angegeben wird, wird der erste Eintrag
zurückgegeben.
Falls der Eintrag länger als 255 Zeichen ist, werden nur
die ersten 255 Zeichen übernommen.
----------------------------
GetEnvData
Funktion: Ermittelt die Daten des akt. Envrionments
Ausgabe: CF = 0 ->> okay
AX = Länge des Environments in Byte
BX = Anzahl der belegten Bytes
CX = Anzahl der freien Bytes
CF = 1 ->> Fehler
----------------------------
EnvCount
Funktion: Ermittelt die Anzahl der Einträge im akt. Environment
Ausgabe: CF = 0 ->> okay
AX = Anzahl der Einträge
CF = 1 ->> Fehler
----------------------------
UsedEnvSeg?
Funktion: Ermittelt das aktuelle Environment-Segment
Ausgabe: AL = 0 ->> lokales Environment
AL = 1 ->> Caller-Environment
AL = 2 ->> Master-Environment
und
CF = 0 ->> akt. Environment noch gültig
CF = 1 ->> akt. Environment ungültig
----------------------------
UseOtherEnv
Funktion: Umsetzen der Routinen auf ein best. Environment
Eingabe: AL = 0 ->> benutze lokales Environment
AL = 1 ->> benutze Caller-Environment
AL = 2 ->> benutze Master-Environment
sonst Fehler
Ausgabe: CF = 0 ->> okay
CF = 1 ->> Fehler, angegebenes Environment nicht
gültig oder falsche Nummer angegeben
akt. Environment wurde nicht geändert
----------------------------
FreeLokalEnv
Funktion: Lokales Environment freigeben
Ausgabe: CF = 0 ->> okay
CF = 1 ->> Fehler
AX = DOS-Fehlernummer
oder
AX = 0FFFFh falls das Segment schon freigegeben
wurde
----------------------------
Upcase
Funktion: Konvertierung des Zeichens in AL in einen Großbuchstaben
Berücksichtigt die Umlaute ä, ö und ü (ß bleibt ß)
Eingbabe: AL = zu konvertierendes Zeichen
Ausgabe: AL = konvertiertes Zeichen
----------------------------
ParseStr
Funktion: Trennt einen String ab einem vorgegebenen Zeichen
Eingabe: DS:SI -> Quellstring
ES:DI -> Puffer für den Zielstring.
AL = Trennzeichen (wird in keinen Teil übernommen!)
Ausgabe: DS:SI -> vorderer Teil
ES:DI -> hinterer Teil
Bes.:
Zielstring muß ungleich Quellstring sein, bei mehreren Vor-
kommen des Trennzeichens wird beim ersten Vorkommen getrennt
----------------------------
DOSStrToStr
Funktion: Konvertierung eines DOS-Strings ins String-Format
(mit Zähler, ohne das Zeichen '$' bzw. ein 0-Byte
am Ende)
Eingabe: DS:SI -> Quellstring
ES:DI -> Zielstring (wird auf max. 255 Byte gekürzt)
AL = Ende-Kennzeichen (0-Byte oder '$')
Bes.: Zielstring gleich Quellstring ist nicht erlaubt.
Falls der Quellstring mehr als 255 Zeichen hat, werden
nur die ersten 255 Zeichen übernommen.
----------------------------
GetCallerName
Funktion: Ermittelt den Namen des aufrufenden Programmes
Eingabe: ES:DI -> Puffer für den Namen als String
Ausgabe: CF = 0 ->> okay
ZF = 0 ->> ES:DI -> Name
ZF = 1 ->> ES:DI -> leerer String, Programm wurde
vom COMMAND.COM aufgerufen.
CF = 1 ->> Fehler
----------------------------
GetProgName
Funktion: Ermittelt den Programm-Namen aus dem Environment
Eingabe: ES:DI = Puffer für den Namen als String
Ausgabe: CF = 0 ->> okay
ZF = 0 ->> ES:DI -> Name des Programms
ZF = 1 ->> ES:DI -> leerer String, Name konnte
nicht ermittelt werden
CF = 1 ->> Fehler
----------------------------
InitEnvRoutines
Funktion: Initialisieren der Variablen
ACHTUNG: Nach Aufruf dieser Routine sind alle Daten auf
die Werte wie nach dem erstmaligen Aufruf einer
Routine aus dieser Bibliothek zurückgesetzt!